@dinoxx/dinox-cli 1.0.20 → 1.0.22

package/README.md

@@ -1,6 +1,6 @@
 # Dinox CLI 用户手册
 
-`dino` 是 Dinox 的命令行工具，用来在本地管理和同步你的 Dinox 数据，包括：笔记、待办、标签、卡片盒、Prompt、知识图谱，以及给 AI 客户端使用的 MCP 服务。
+`dino` 是 Dinox 的命令行工具，用来在本地管理和同步你的 Dinox 数据，包括：笔记、待办、标签、卡片盒、Prompt、知识图谱，以及适合脚本和 AI 助手调用的结构化命令输出。
 
 这份 README 按“先上手、再进阶、最后查表”的顺序重写，尽量做到：
 
@@ -20,7 +20,7 @@
 - [4. 使用前必须知道的 6 个规则](#4-使用前必须知道的-6-个规则)
 - [5. 日常操作教程](#5-日常操作教程)
 - [6. 完整命令速查](#6-完整命令速查)
-- [7. AI / Cursor / MCP 集成](#7-ai--cursor--mcp-集成)
+- [7. AI / 脚本自动化](#7-ai--脚本自动化)
 - [8. 常见问题](#8-常见问题)
 - [9. 配置文件、数据库与环境变量](#9-配置文件数据库与环境变量)
 - [10. 如何查看帮助](#10-如何查看帮助)
@@ -36,14 +36,13 @@ Dinox CLI 适合这几类场景：
 3. 从笔记里的任务列表中搜索待办，或追加/创建待办
 4. 维护标签、卡片盒、Prompt 等结构化信息
 5. 查询笔记之间的链接关系和知识图谱
-6. 给 Cursor / AI Agent 暴露 MCP 工具接口
-7. 用 `--format json` 输出结构化结果，方便脚本和 AI 调用
+6. 用 `--format json` 输出结构化结果，方便脚本和 AI 调用
 
 你可以把它理解为：
 
 - 普通用户：一个更高效的 Dinox 数据管理工具
 - 进阶用户：一个可脚本化的本地知识库命令行入口
-- AI 用户：一个可被 MCP / 自动化工具调用的本地数据服务入口
+- AI 用户：一个可通过结构化命令和 schema 稳定调用的本地知识库入口
 
 ---
 
@@ -121,8 +120,9 @@ dino auth login "<你的 token>"
 说明：
 
 - 这里填的是登录 token 本体
-- 不要加 `Bearer ` 前缀
+- `dino auth login` 建议传 token 本体，不要加 `Bearer ` 前缀
 - 登录时 CLI 会顺便验证连接是否可用
+- 自动化或 CI 可以改用 `DINOX_TOKEN` 环境变量注入 token；它优先于本地配置，并支持 token 本体或 `Bearer ...`
 
 ### 第 2 步：同步数据到本地
 
@@ -409,52 +409,57 @@ dino note create \
   --dry-run
 ```
 
-### 5.4 更新笔记标签、卡片盒、收藏状态
+### 5.4 整理笔记元数据与正文
 
-#### 更新单条笔记的标签
+#### `note update`：显式 ID 的全量替换
 
 ```bash
-dino note update <note-id> --tags "工作,AI"
+dino note update <note-id> --tags "工作,AI" --dry-run
+dino note update <note-id> --boxes "Inbox" --starred true --dry-run
 ```
 
-#### 更新单条笔记的卡片盒
+`note update` 面向明确的笔记 ID，`--tags` 和 `--boxes` 都是完整替换，不是追加。清空标签或卡片盒时传 `[]`：
 
 ```bash
-dino note update <note-id> --boxes "Inbox"
+dino note update <note-id> --tags '[]'
+dino note update <note-id> --boxes '[]'
 ```
 
-#### 设置收藏状态
+#### `note tag` / `note move`：显式 ID 的增量整理
 
 ```bash
-dino note update <note-id> --starred true
-dino note update <note-id> --starred false
+dino note tag <note-id> --add "工作,AI" --dry-run
+dino note tag --ids @./note-ids.txt --remove "Inbox" --dry-run
+dino note move <note-id> --add "Project/Inbox" --dry-run
+dino note move --ids @./note-ids.txt --replace "Project" --dry-run
 ```
 
-#### 使用专门的收藏命令
+`note tag` 管标签，`note move` 管卡片盒归属；它们的 `--add` / `--remove` 会保留现有值，`--replace` 才会覆盖整个列表。`note move` 不移动文件，也不改正文。
+
+#### `note bulk`：按过滤器批量整理
 
 ```bash
-dino note star <note-id>
-dino note unstar <note-id>
+dino note bulk --tags "Inbox" --tag-add "AI" --format json --dry-run
+dino note bulk --days 30 --boxes "Work/Inbox" --box-replace "Archive/Review" --expected-count 12 --confirm --format json
 ```
 
-#### 批量更新多条笔记
+`note bulk` 只接受受控过滤器，不支持 `--sql` 作为写入目标筛选。真实写入必须先 dry-run，再带 `--confirm --expected-count <n>`。
+
+#### `note patch`：结构化编辑正文
 
 ```bash
-dino note update --ids @./note-ids.txt --boxes "Project"
-dino note star --ids @./note-ids.txt
+dino note content-read <note-id> --format json
+dino note patch <note-id> --append-section "复盘" --content @./section.md --read-token <token> --format json
 ```
 
-重要说明：
+`note patch` 只用于正文结构化编辑。真实写入前必须先 `content-read`，并传回 `readToken`；替换媒体、表格、未知节点等受保护 block 时，还需要显式 `--allow-protected-replace`。
 
-- `note update` 是“全量替换”标签/卡片盒，不是追加
-- 如果你传 `--tags "工作,AI"`，最终标签就会变成这两个
-- 如果你想清空标签或卡片盒，可以传 `[]`
-
-例如：
+#### 收藏状态
 
 ```bash
-dino note update <note-id> --tags '[]'
-dino note update <note-id> --boxes '[]'
+dino note star <note-id>
+dino note unstar <note-id>
+dino note star --ids @./note-ids.txt
 ```
 
 ### 5.5 删除笔记
@@ -858,27 +863,7 @@ dino schema todo.update --format json
 - 你要让 AI / 脚本可靠调用 CLI
 - 你想快速查看命令风险级别、输出结构、示例
 
-### 6.14 `mcp`：启动 MCP 服务
-
-```bash
-dino mcp serve
-dino mcp serve --host 127.0.0.1 --port 45137
-```
-
-如果绑定到非本机地址（例如 `0.0.0.0`），必须提供 token：
-
-```bash
-dino mcp serve --host 0.0.0.0 --port 45137 --token "<your-token>"
-```
-
-或使用环境变量：
-
-```bash
-export DINOX_MCP_TOKEN="<your-token>"
-dino mcp serve --host 0.0.0.0 --port 45137
-```
-
-### 6.15 `daemon`：管理后台进程
+### 6.14 `daemon`：管理后台进程
 
 ```bash
 dino daemon start
@@ -893,113 +878,59 @@ dino daemon stop
 dino daemon start --no-detach
 ```
 
-### 6.16 `info`：查看版本与技能仓库地址
-
-```bash
-dino info
-```
-
-### 6.17 `update`：升级 CLI
-
-```bash
-dino update
-```
-
----
-
-## 7. AI / Cursor / MCP 集成
-
-如果你希望让 Cursor、MCP Client 或其他 AI 工具直接调用 Dinox 数据，这一节最重要。
-
-### 7.1 启动 MCP 服务
-
-默认只监听本机回环地址：
+`daemon` 是公开 CLI 模块，也可以通过 schema 查询：
 
 ```bash
-dino mcp serve
+dino schema daemon.start --format json
 ```
 
-默认地址通常是：
-
-- Host：`127.0.0.1`
-- Port：`45137`
-
-手动指定地址和端口：
+### 6.15 `info`：查看版本与技能仓库地址
 
 ```bash
-dino mcp serve --host 127.0.0.1 --port 45137
+dino info
 ```
 
-### 7.2 非本机访问时必须加 token
-
-如果你不是监听 `127.0.0.1` / `localhost`，而是希望局域网其他机器访问，那么必须加 token。
+### 6.16 `update`：升级 CLI
 
 ```bash
-dino mcp serve --host 0.0.0.0 --port 45137 --token "<your-token>"
+dino update
 ```
 
-服务端支持以下鉴权头：
+---
 
-1. `Authorization: Bearer <token>`
-2. `x-dinox-token: <token>`
+## 7. AI / 脚本自动化
 
-### 7.3 用 curl 快速测试连通性
+如果你希望让 AI 助手或脚本可靠调用 Dinox 数据，推荐直接使用 CLI 命令的结构化输出。
 
-#### 初始化握手
+### 7.1 使用 JSON 输出
 
 ```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+dino note search "dinox" --limit 5 --format json
+dino note detail <id> --format json
+dino todo search --status uncompleted --format json
 ```
 
-#### 列出工具
+`--format json` 会返回稳定的结构化 envelope，适合被脚本、自动化任务和 AI Agent 解析。
 
-```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
-```
+### 7.2 先读取命令 schema
 
-#### 调用一个工具（示例：搜索笔记）
+不确定某个命令支持哪些参数、输出哪些字段时，先读取 schema：
 
 ```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dinox_search_notes","arguments":{"query":"dinox","limit":5}}}'
-```
-
-### 7.4 Cursor 配置示例
-
-你可以在以下任一位置创建 MCP 配置文件：
-
-1. 项目级：`.cursor/mcp.json`
-2. 全局：`~/.cursor/mcp.json`
-
-示例配置：
-
-```json
-{
-  "mcpServers": {
-    "dinox": {
-      "url": "http://127.0.0.1:45137",
-      "headers": {
-        "Authorization": "Bearer ${env:DINOX_MCP_TOKEN}"
-      }
-    }
-  }
-}
+dino schema
+dino schema note.search --format json
+dino schema todo.update --format json
 ```
 
-如果你只在本机回环地址使用，而且服务端没有启用 token，那么可以不写 `headers`。
+schema 包含命令路径、风险级别、参数、选项、输出字段和示例。写操作建议先使用 `--dry-run` 确认结果。
 
 ---
 
 ## 8. 常见问题
 
-### Q1：报错 `Missing persisted userId. Run dino auth login first.`
+### Q1：报错 `Missing resolved userId for the current authorization`
 
-原因：你还没有完成登录，或登录信息没有成功保存。
+原因：你还没有完成登录，或当前 `DINOX_TOKEN` 环境变量覆盖了本地 token，CLI 需要先在线解析这个 token 对应的用户身份。
 
 解决：
 
@@ -1008,6 +939,13 @@ dino auth login "<token>"
 dino sync
 ```
 
+如果你使用环境变量登录，确认 `DINOX_TOKEN` 已设置后直接运行一次在线命令：
+
+```bash
+dino auth status --format json
+dino sync
+```
+
 ### Q2：创建笔记时报 `Unknown tags` 或 `Unknown zettel box names`
 
 原因：你引用了不存在的标签或卡片盒。
@@ -1048,6 +986,12 @@ dino note update <note-id> --tags "工作,AI"
 
 执行后，目标笔记的标签会被替换成这两个，而不是在原来基础上追加。
 
+追加标签请使用：
+
+```bash
+dino note tag <note-id> --add "工作,AI"
+```
+
 ### Q5：`todo append` 不传 `--note-id` 时会发生什么？
 
 CLI 会自动选一条最近的、适合追加任务的笔记作为目标。
@@ -1068,17 +1012,7 @@ dino todo append --note-id <note-id> --task "补交报销单"
 dino note create --title "测试" --content "@.\note.md" --type note
 ```
 
-### Q7：`mcp serve` 绑定 `0.0.0.0` 时为什么报 token 错误？
-
-因为只要不是本机回环地址，就必须提供鉴权 token。
-
-例如：
-
-```bash
-dino mcp serve --host 0.0.0.0 --port 45137 --token "<your-token>"
-```
-
-### Q8：怎么知道某个命令到底支持哪些参数？
+### Q7：怎么知道某个命令到底支持哪些参数？
 
 最直接的方法：
 
@@ -1121,9 +1055,8 @@ dino schema todo.update --format json
 | --- | --- |
 | `DINOX_CONFIG_DIR` | 覆盖配置目录 |
 | `DINOX_DATA_DIR` | 覆盖本地数据目录 |
-| `DINOX_AUTHORIZATION` | 用环境变量注入登录 token |
+| `DINOX_TOKEN` | 用环境变量注入登录 token，优先级高于本地配置；可传 token 本体或 `Bearer ...` |
 | `DINOX_SYNC_TIMEOUT_MS` | 覆盖同步超时 |
-| `DINOX_MCP_TOKEN` | 给 `dino mcp serve` 提供默认 token |
 
 ### 9.3 macOS / Linux 与 Windows 的多行命令差异
 
@@ -1186,6 +1119,6 @@ dino schema <path> --format json
 4. `dino note create`
 5. `dino todo search`
 6. `dino tag add` / `dino box add`
-7. `dino mcp serve`
+7. `dino schema`
 
 这样会最快建立完整使用感。

package/dist/auth/userInfo.d.ts

@@ -14,4 +14,11 @@ export declare function fetchUserInfoWithAuthorization(input: {
     signal?: AbortSignal;
 }): Promise<AuthIdentity>;
 export declare function refreshAndPersistAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;
-export declare function resolveAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;
+export declare function hydrateResolvedAuthIdentity(resolvedConfig: ResolvedDinoxConfig, options?: {
+    timeoutMs?: number;
+}): Promise<{
+    config: ResolvedDinoxConfig;
+    identity: AuthIdentity | null;
+    hydrated: boolean;
+}>;
+export declare function resolveAuthIdentity(resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;

package/dist/auth/userInfo.js

@@ -136,16 +136,48 @@ export async function refreshAndPersistAuthIdentity(rawConfig, resolvedConfig) {
     await saveConfig(nextConfig);
     return identity;
 }
-export async function resolveAuthIdentity(rawConfig, resolvedConfig) {
-    const savedUserId = normalizeOptionalString(rawConfig.auth?.userId ?? resolvedConfig.auth.userId);
-    const syncedAt = normalizeOptionalString(rawConfig.auth?.userInfoSyncedAt ?? resolvedConfig.auth.userInfoSyncedAt);
+function authIdentityFromResolvedConfig(resolvedConfig) {
+    const savedUserId = normalizeOptionalString(resolvedConfig.auth.userId);
+    const syncedAt = normalizeOptionalString(resolvedConfig.auth.userInfoSyncedAt);
     if (savedUserId) {
         return {
             userId: savedUserId,
-            username: normalizeOptionalNullableString(rawConfig.auth?.username ?? resolvedConfig.auth.username),
-            email: normalizeOptionalNullableString(rawConfig.auth?.email ?? resolvedConfig.auth.email),
+            username: normalizeOptionalNullableString(resolvedConfig.auth.username),
+            email: normalizeOptionalNullableString(resolvedConfig.auth.email),
             syncedAt: syncedAt ?? new Date().toISOString(),
         };
     }
-    throw new DinoxError('Missing persisted userId. Run `dino auth login` first.');
+    return null;
+}
+export async function hydrateResolvedAuthIdentity(resolvedConfig, options = {}) {
+    const existing = authIdentityFromResolvedConfig(resolvedConfig);
+    if (existing || !resolvedConfig.auth.authorization) {
+        return { config: resolvedConfig, identity: existing, hydrated: false };
+    }
+    const identity = await fetchUserInfoWithAuthorization({
+        authorization: resolvedConfig.auth.authorization,
+        config: resolvedConfig,
+        timeoutMs: options.timeoutMs,
+    });
+    return {
+        config: {
+            ...resolvedConfig,
+            auth: {
+                ...resolvedConfig.auth,
+                userId: identity.userId,
+                username: identity.username,
+                email: identity.email,
+                userInfoSyncedAt: identity.syncedAt,
+            },
+        },
+        identity,
+        hydrated: true,
+    };
+}
+export async function resolveAuthIdentity(resolvedConfig) {
+    const identity = authIdentityFromResolvedConfig(resolvedConfig);
+    if (identity) {
+        return identity;
+    }
+    throw new DinoxError('Missing resolved userId for the current authorization. Run `dino auth login` first, or set DINOX_TOKEN and run an online command so the CLI can resolve the token identity.');
 }

package/dist/cli.js

@@ -5,7 +5,6 @@ import { registerConfigCommands } from './commands/config/index.js';
 import { registerDaemonCommands } from './daemon/index.js';
 import { registerGraphCommands } from './commands/graph/index.js';
 import { registerInfoCommand } from './commands/info/index.js';
-import { registerMCPCommands } from './commands/mcp/index.js';
 import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
@@ -29,6 +28,7 @@ export function createCli() {
         .option('--json', 'legacy machine-readable YAML output (equivalent to --format yaml)')
         .option('--format <format>', 'structured output format: yaml | json')
         .option('--offline', 'skip connect/sync and only use local cache')
+        .option('--require-sync', 'fail if the local PowerSync cache cannot be confirmed fresh before reading')
         .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
         .option('--verbose', 'enable verbose logging');
     program.hook('preAction', (_thisCommand, actionCommand) => {
@@ -44,7 +44,6 @@ export function createCli() {
     registerDaemonCommands(program);
     registerGraphCommands(program);
     registerInfoCommand(program);
-    registerMCPCommands(program);
     registerMetaCommands(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);

package/dist/cliTypes.d.ts

@@ -1,6 +1,7 @@
 export type GlobalOptions = {
     json?: boolean;
     offline?: boolean;
+    requireSync?: boolean;
     syncTimeout?: string;
     verbose?: boolean;
 };

package/dist/commands/auth/index.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs/promises';
-import { buildPendingAuthConfig, fetchUserInfoWithAuthorization, mergeAuthIdentityIntoConfig, } from '../../auth/userInfo.js';
+import { buildPendingAuthConfig, fetchUserInfoWithAuthorization, hydrateResolvedAuthIdentity, mergeAuthIdentityIntoConfig, } from '../../auth/userInfo.js';
 import { getLegacyPowerSyncDbPath, getPowerSyncDbPath } from '../../config/paths.js';
 import { loadConfig, saveConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
@@ -8,7 +8,7 @@ import { connectPowerSync, getStatusSnapshot } from '../../powersync/runtime.js'
 import { runSingleSyncPass } from '../../powersync/syncPass.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
-import { normalizeAuthToken } from '../../utils/authToken.js';
+import { normalizeAuthToken, readEnvAuthToken } from '../../utils/authToken.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
 import { redactAuthorization } from '../../utils/redact.js';
@@ -26,6 +26,10 @@ async function runAuthLogin(context) {
     if (!rawToken) {
         throw new DinoxError('Token is required');
     }
+    const envToken = readEnvAuthToken();
+    if (envToken && envToken !== rawToken) {
+        throw new DinoxError('DINOX_TOKEN is set and differs from the login token. Unset DINOX_TOKEN before running `dino auth login`, or use the same token.');
+    }
     const previousConfig = await loadConfig();
     const pendingConfig = buildPendingAuthConfig(previousConfig, rawToken);
     const resolved = resolveConfig(pendingConfig);
@@ -107,10 +111,13 @@ async function runAuthLogout(context) {
 }
 async function runAuthStatus(context) {
     const config = await loadConfig();
-    const resolved = resolveConfig(config);
+    const baseResolved = resolveConfig(config);
     const offline = Boolean(context.globals.offline);
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? resolved.sync.timeoutMs;
+    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? baseResolved.sync.timeoutMs;
+    const { config: resolved } = offline
+        ? { config: baseResolved }
+        : await hydrateResolvedAuthIdentity(baseResolved, { timeoutMs });
     const dbPath = getPowerSyncDbPath(resolved.auth.userId);
     const base = {
         loggedIn: Boolean(resolved.auth.authorization),